home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 7: Sunsite / Linux Cubed Series 7 - Sunsite Vol 1.iso / system / admin / time / adjtimex.2 / adjtimex / README < prev   
Text File  |  1995-03-17  |  6KB  |  191 lines
  1. ADJTIMEX 
  2.  
  3. I will assume you have already read the man page for adjtimex :-)
  4.  
  5.  
  6. BACKGROUND
  7.  
  8. You probably already know that your computer has two clocks - the "real
  9. time clock" (RTC) that runs all the time, and the system clock that runs
  10. only while the computer is on.  The system clock has much better
  11. precision (approximately 1 usec), but the RTC probably has better
  12. long-term stability.  adjtimex can be used to approximately correct the
  13. system clock for drift.
  14.  
  15. The handiest reference clock is the RTC.  I have included the small
  16. program clockdiff which shows the time, the difference between the two
  17. clocks, the first difference (how much the system clock has gained or
  18. lost relative to the RTC since the last check), and two kernel time
  19. parameters: tick and frequency offset.  Of course, the RTC probably has
  20. a systematic error of its own.  clock(8) uses the file /etc/adjtime to
  21. record the drift rate and the time since the RTC was last set.
  22. clockdiff uses the same file.
  23.  
  24.  
  25. INSTALLATION
  26.  
  27. Type "make" to compile, then copy the binary to /sbin, and the man page
  28. to /usr/man/man8 or wherever.
  29.  
  30.  
  31. ASIDES
  32.  
  33. You will have to log in as root for most of the following.
  34.  
  35. The standard kernel will leave the RTC alone only until one of the time
  36. parameters is set (using adjtimex, for example).  Then it thinks xntpd
  37. is regulating the system time, and it starts "correcting" the RTC
  38. approximately every ten minutes.  You can prevent this by setting the
  39. parameter "status" to 4.  I will include this in every command line.
  40.  
  41.  
  42. USAGE
  43.  
  44. Create /etc/adjtime.  clockdiff uses the file /etc/adjtime to correct
  45. for systematic error in the RTC.  Set it up as explained in the man page
  46. for clock(8).  clock (and a lot of other useful utilities) is included
  47. in Rik Faith's collection:
  48. sunsite.unc.edu:pub/Linux/system/Misc/util-linux-1.10.tar.gz If your RTC
  49. is already accurate enough to suit you, just create a file /etc/adjtime
  50. containing as the first and only line: '0.0 0 0.0'.
  51.  
  52.  
  53. Compile clockdiff, run it, and let it report twice, ten seconds apart
  54. (you will have to interrupt it with ^C).  Suppose the result is:
  55.  
  56. # ./clockdiff -p 10
  57. 794625929   -0.597638 -0.597638         0     10000         0
  58. 794625939   -0.602050 -0.004412         0     10000         0
  59.                       ^^^^^^^^^
  60. This number says the system clock lost over 4 msec in just 10 sec with
  61. respect to the RTC, or 4 parts in 10000.  Therefore, we increase the
  62. tick parameter to 10004, and repeat the comparison:
  63.  
  64. # adjtimex -status 4  -tick 10004
  65. # ./clockdiff -p 10
  66. 794626037   -0.644860 -0.644860         0     10004         0
  67. 794626047   -0.645259 -0.000399         0     10004         0
  68.  
  69. Now the system clock is slow by about 39.9 parts per million.  We can
  70. change the frequency offset to fix this.  Recall that the frequency
  71. offset is in parts per million, with the fraction point in the center
  72. (16 bits on either side).  Therefore, we set the offset to 39.9*65536 =
  73. 2614886:
  74.  
  75. # adjtimex -status 4  -frequency 2614886
  76. # ./clockdiff -p 10
  77. 794626313   -0.652147 -0.652147   2614886     10004         0
  78. 794626323   -0.652247 -0.000100   2614886     10004         0
  79.  
  80. It still seems to be off by about 10 ppm, so we increase the offset
  81. by 10*65536, to 3270246:
  82.  
  83. # adjtimex -status 4  -frequency 3270246
  84. # ./clockdiff -p 10
  85. 794627233   -0.795221 -0.795221   3270246     10004         0
  86. 794627243   -0.795231 -0.000009   3270246     10004         0
  87.  
  88. Continue until you're satisfied (or tired :-).  
  89.  
  90. By the way, using the -offset or -singleshot options seems to have a
  91. long-term effect on the clock.  I suggest you determine the tick and
  92. frequency settings before trying the other options.
  93.  
  94.  
  95. You may already have an entry like this in rc.S or one of the
  96. other startup files:
  97.  
  98.     # Adjust CMOS clock based on /etc/adjtime, then set system clock.
  99.     # Add -u switch if your system keeps GMT.
  100.     if [ -x /sbin/clock ]; then
  101.       /sbin/clock -a
  102.     fi
  103.  
  104.  
  105. Just add an entry like this:
  106.  
  107.     # Regulate the sytem clock
  108.     if [ -x /sbin/adjtimex ]; then
  109.       /sbin/adjtimex  -tick 10004  -frequency 3270246  -status 4
  110.     fi
  111.  
  112.  
  113. THE PATCH
  114.  
  115. As mentioned in the man page, the -status and -singleshot options
  116. interfere.  The following kernel patch eliminates this problem, and adds
  117. some checks that were suggested in the original code:
  118.  
  119. diff -u -r linux-1.1.93.orig/kernel/time.c linux-1.1.93/kernel/time.c
  120. --- linux-1.1.93.orig/kernel/time.c    Wed Feb  1 02:19:36 1995
  121. +++ linux-1.1.93/kernel/time.c    Wed Feb 22 20:54:22 1995
  122. @@ -16,6 +16,8 @@
  123.   *      adjtime interface update and CMOS clock write code
  124.   * 02 Jul 94    Alan Modra
  125.   *    fixed set_rtc_mmss, fixed time.year for >= 2000, new mktime
  126. + * 22 Feb 95    Jim Van Zandt
  127. + *    adjtime mode tests fixed
  128.   */
  129.  
  130.  #include <linux/errno.h>
  131. @@ -348,11 +350,19 @@
  132.      /* Now we validate the data before disabling interrupts
  133.       */
  134.  
  135. -    if (txc.mode != ADJ_OFFSET_SINGLESHOT && (txc.mode & ADJ_OFFSET))
  136. +    if ((txc.mode & ADJ_OFFSET) &&
  137. +        ((txc.mode & ADJ_OFFSET_SINGLESHOT) != ADJ_OFFSET_SINGLESHOT)) {
  138. +
  139. +      /* if applying offset, can't change other variables too */
  140. +      /* XXX should give error for setting any other bits? */
  141. +      if (txc.mode & ADJ_TICK || txc.mode & ADJ_FREQUENCY)
  142. +        return -EINVAL;
  143. +
  144.        /* Microsec field limited to -131000 .. 131000 usecs */
  145.        if (txc.offset <= -(1 << (31 - SHIFT_UPDATE))
  146.            || txc.offset >= (1 << (31 - SHIFT_UPDATE)))
  147.          return -EINVAL;
  148. +    }
  149.  
  150.      /* time_status must be in a fairly small range */
  151.      if (txc.mode & ADJ_STATUS)
  152. @@ -391,7 +401,7 @@
  153.          time_constant = txc.time_constant;
  154.  
  155.          if (txc.mode & ADJ_OFFSET)
  156. -          if (txc.mode == ADJ_OFFSET_SINGLESHOT)
  157. +          if ((txc.mode & ADJ_OFFSET_SINGLESHOT) == ADJ_OFFSET_SINGLESHOT)
  158.          {
  159.            time_adjust = txc.offset;
  160.          }
  161.  
  162.  
  163. FURTHER READING
  164.  
  165. For authoritative documentation on the kernel time software, see
  166. the following, all by David L. Mills <mills@udel.edu>:
  167.  
  168. [MIL92a] Mills, D.L. Network Time Protocol (Version 3) specification,
  169. implementation and analysis, RFC 1305, University of Delaware, March
  170. 1992, 113 pp.
  171.  
  172. [MIL92c] Mills, D.L. Simple Network Time Protocol (SNTP), RFC 1361,
  173. University of Delaware, August 1992, 10 pp.
  174.  
  175. [MIL94a] Mills, D.L. A kernel model for precision timekeeping. ARPA
  176. Network Working Group Report RFC-1589, University of Delaware, March
  177. 1994. 31 pp.
  178.  
  179. README.kern, which can be found in louie.udel.edu:/pub/ntp/kernel.tar.Z.
  180.  
  181.  
  182. THANKS
  183.  
  184. to David Mills for the kernel timekeeping code, and Steven Dick for
  185. writing adjtimex.
  186.  
  187.  
  188. Enjoy!
  189.                 - Jim Van Zandt <jrv@vanzandt.mv.com>
  190.  
  191.